Error Handling CGI

This lesson will teach you how to create a CGI application that returns information even if an error occurs. In previous scripts, if an error occured the system might beep on the server, but all the user gets is a long (long) wait followed by an uninformative error message. With this system, a useful error message is returned that informs the user of what kind of error occured and what the offending application was. This information can then be mailed back to the Webmaster. It also ensures that the server isn't tied up by a faulty script.

Required OSAX

ScriptTools

NOTE: if you have not yet installed this OSAX, then do it before starting this lesson. The script will not compile without it. Go back to the Requirements section to download the OSAX if you need it.

Script3.txt - An Error Handling CGI

Here is the entire script for this lesson. The comments have been removed so you see only the lines that actually get compiled. The full script, including comments and special characters, is in the archive with the name "Script3.txt".

property crlf : (ASCII character 13) & (ASCII character 10)
property http_10_header : "HTTP/1.0 200 OK" & crlf & "Server: WebSTAR/1.0 ID/ACGI" & crlf & ¬
   "MIME-Version: 1.0" & crlf & "Content-type: text/html" & crlf & crlf
property idletime : 1800
property datestamp : 0

set datestamp to current date

on «event WWWΩsdoc» path_args ¬
   given «class kfor»:http_search_args, «class post»:post_args, «class meth»:method, «
      class addr»:client_address, «class user»:username, «class pass»:password, «class frmu»:from_user, «
      class svnm»:server_name, «class svpt»:server_port, «class scnm»:script_name, «
      class ctyp»:content_type, «class refr»:referer, «class Agnt»:user_agent, «
      class Kact»:action, «class Kapt»:action_path, «class Kcip»:client_ip, «class Kfrq»:full_request
	
   try
	
   set datestamp to current date

   set return_page to http_10_header ¬
      & "<HTML><HEAD><TITLE>Unprocessed Results</TITLE></HEAD>" ¬
      & "<BODY><H1>Unprocessed Results</H1>" & return ¬
      & "<H4>path_args</H4>" & return & path_args & return ¬
      & "<H4>http_search_args</H4>" & return & http_search_args
   set return_page to return_page & return ¬
      & "<H4>post_args</H4>" & return & post_args & return ¬
      & "<H4>method</H4>" & return & method & return ¬
      & "<H4>client_address</H4>" & return & client_address & return ¬
      & "<H4>username</H4>" & return & username & return ¬
      & "<H4>password</H4>" & return & password & return
   set return_page to return_page & return ¬
      & "<H4>from_user</H4>" & return & from_user & return ¬
      & "<H4>server_name</H4>" & return & server_name & return ¬
      & "<H4>server_port</H4>" & return & server_port & return ¬
      & "<H4>script_name</H4>" & return & script_name & return ¬
      & "<H4>content_type</H4>" & return & content_type & return ¬
      & "<H4>referer</H4>" & return & referer & return
   set return_page to return_page & return ¬
      & "<H4>user_agent</H4>" & return & user_agent & return ¬
      & "<H4>action</H4>" & return & action & return ¬
      & "<H4>action_path</H4>" & return & action_path & return ¬
      & "<H4>client_ip</H4>" & return & client_ip & return ¬
      & "<H4>full_request</H4>" & return & full_request & return
   set return_page to return_page ¬
      & "<I>Results generated at: " & (current date) ¬
      & "</I>" & "</BODY></HTML>"   return return_page

 on error errMsg number errNum
   set return_page to http_10_header ¬
      & "<HTML><HEAD><TITLE>Error Page</TITLE></HEAD>" ¬
      & "<BODY><H1>Error Encountered!</H1>" & return ¬
      & "An error was encountered while trying to run this script." & return
   set return_page to return_page ¬
      & "<H3>Error Message</H3>" & return & errMsg & return ¬
      & "<H3>Error Number</H3>" & return & errNum & return ¬
      & "<H3>Date</H3>" & return & (current date) & return
   set return_page to return_page ¬
      & "<HR>Please notify Mr. Webmaster at " ¬
      & "<A HREF=\"mailto:webmaster@this.site.com\">webmaster@this.site.com</A>" ¬
      & " of this error." & "</BODY></HTML>"   return return_page

   end try
end «event WWWΩsdoc»

on idle
   if (current date) > (datestamp + idletime) then
      quit
   end if
   return 5
end idle

on quit
   continue quit
end quit

Step By Step

There are only two additions to this script. Let's take a look at them.

try

This line, added at the start of the Apple event handler, tells AppleScript that you have provided an error handler (see below) in the event of an error. The usual "try" statement looks like the following:

   try
      [some statements to try to do without error]
   on error
      [statements to do if an error occurs]
   end try

The "on error" handler is part of the try statement. Therefore, the "end try" line ends the whole statement, including the error handler.

 	on error errMsg number errNum
   set return_page to http_10_header ¬
      & "<HTML><HEAD><TITLE>Error Page</TITLE></HEAD>" ¬
      & "<BODY><H1>Error Encountered!</H1>" & return ¬
      & "An error was encountered while trying to run this script." & return
   set return_page to return_page ¬
      & "<H3>Error Message</H3>" & return & errMsg & return ¬
      & "<H3>Error Number</H3>" & return & errNum & return ¬
      & "<H3>Date</H3>" & return & (current date) & return
   set return_page to return_page ¬
      & "<HR>Please notify Mr. Webmaster at " ¬
      & "<A HREF=\"mailto:webmaster@this.site.com\">webmaster@this.site.com</A>" ¬
      & " of this error." & "</BODY></HTML>"   return return_page
	end try

This is the error handling code. If an error occurs after the try statement, this handler is run. It is passed a number of variables. Here we are using just the two standard parameters:

errMsg: This contains the message sent by whatever generated the error (the System or AppleScript).
errNum: This contains the number of the error. Most System and AppleScript errors are negative numbers.

There are other parameters that can be used, such as suspect, which lists the offending object, and partial_results, which lists the information processed so far. These can be very useful, but are more difficult to use. Consult your AppleScript book about these (actually, my books say very little about them). It is possible for you to call the error handler on your own and pass in your own error message and number. In fact, this is recommended when you are debugging AppleScript code, as quite a bit can go wrong without generating a serious error. The file "Script3.txt" that is included in the archive does exactly this to show how the error page looks.

As you can see in the code above, nothing is really new in this handler. All it does is create an HTML page to return that contains the error information. By passing back an HTML page, the user gets two benefits:

The user gets some idea of what happened and can make a decision based on that of whether to try again or not.
The CGI finishes processing instead of hanging until a timeout occurs. This means the user is freed up much sooner.

These are both "Very Good Things" for everyone involved. Your WebSTAR server will thank you. Your user will thank you. Your service provider may even thank you (but that's not likely).

Wrap It Up

Again, this code should be easy to paste into any of your existing scripts that work with WebSTAR. There are a couple of points to make, though, now that you know that there can actually be errors in AppleScript:

This code is still not 100% effective against errors. If AppleScript (or WebSTAR) crashes then you are still stuck, as there will be nothing available with which to return the error information.
Not all error messages are very informative, and the error codes are even less so. You may want to write your own error messages to pass in some instances.
This code returns error information to the user. This does not help you unless you are the user (or the user writes back to you). You may want to have errors logged to a file as well. That is something you'll have to read you AppleScript book to learn to do.

[Go back to Tutorial Index]

Jon Wiederspan
Last Edited: April 26, 1995
Copyright Jon Wiederspan, 1994,1995